﻿//-----------------------------------------------------------------------
// <copyright file="IRuleSetParser.cs" company="tuliprules.org">
//     Copyright (c) 2010 tuplelister, tuliprules.org.
// </copyright>
// <summary>This is the IRuleSetParser interface.</summary>
//-----------------------------------------------------------------------

namespace Tulip.Rules
{
    using System;
    using System.Collections.ObjectModel;

    /// <summary>
    /// Represents a parser for a rule or rule set.  The role of the parser is to
    /// provide the model for a rule or rule set based on content.  The parser can
    /// also reverse-engineer a model to provide content.
    /// </summary>
    public interface IRuleSetParser
    {
        /// <summary>
        /// Gets a URI that can be used as a type specifer for the rule set.
        /// </summary>
        /// <value>
        /// The build component of the version number.
        /// </value>
        Uri RuleSetType
        {
            get;
        }

        /// <summary>
        /// Gets the presentation representation of the rule or rule set.
        /// </summary>
        /// <value>
        /// The content of the rule or rule set.
        /// </value>
        /// <remarks>
        /// The presentation of the rule or rule set is always textual.  It may  
        /// represent an artefact written in a formal rule language or some
        /// non-normative representation of a formal model.</remarks>
        string Presentation
        {
            get;
        }

        /// <summary>
        /// Gets the model representing the rule or rule set.
        /// </summary>
        /// <value>
        /// The model representing the rule or rule set.
        /// </value>
        /// <remarks>
        /// The model represents a rule set in a formal fashion and is designed to
        /// be processed by a rule set transformer.  Typically, the model will be
        /// refernced via a root node object returned by this property.
        /// </remarks>
        object Model
        {
            get;
        }

        /// <summary>
        /// Gets a read-only collection of rules.
        /// </summary>
        /// <value>
        /// A read-only collection of rules.
        /// </value>
        ReadOnlyCollection<Rule> Rules
        {
            get;
        }
    
        /// <summary>
        /// Parses rule content.
        /// </summary>
        /// <param name="content">
        /// The content of the rule or rule set.
        /// </param>
        /// <returns>
        /// True, if parsing completed; false if the parse terminated abnormally.
        /// </returns>
        bool Parse(string content);

        /// <summary>
        /// Parses a rule model.
        /// </summary>
        /// <param name="model">
        /// The model representing the rule or rule set.
        /// </param>
        /// <returns>
        /// True, if parsing completed; false if the parse terminated abnormally.
        /// </returns>
        bool Parse(object model);
    }
}
